Copyright: Copyright © 1996
Citation: Distinct Corporation


Distinct TCP/IP SDK - Standard Edition
Distinct TCP/IP SDK - Standard Edition (32 bit Version)

TCP/IP API’s for Windows Sockets, ONC RPC/XDR, Telnet, FTP, RLIB (Rexec, Rlogin, Rshell and Rcopy), SMTP, POP2 / POP3, MIME, and NNTP for Microsoft Windows 95 and Windows NT.

For more information, click a topic below:

Included Libraries

Function Summaries


FTP Library
The FTP Library

The Distinct FTP library provides a developer with an API to the standard File Transfer Protocol service available on most TCP/IP based hosts. To establish a connection with an FTP server, an application must first call ftp_open. If the FTP service on the remote host does not use the standard FTP port, then the ftp_xopen function can be called to establish a connection with an FTP service on a specific port. Once the ftp_open or the ftp_xopen function returns successfully, a TCP connection has been completed but no login information has been sent.

Next, the ftp_login function must be called. This function specifies the user name and the password to use to log into the server over the previously created connection. Most servers require a password in all cases (for anonymous login, the full e-mail address of the user is often expected as a password). Some servers send out a long introductory message after a successful login. This message is discarded by the FTP library. These servers often accept a hyphen in front of the password as a signal not to send the lengthy login message. Although adding the hyphen may speed up the login process with some servers, others may not accept it at all and reject the login attempt.

If the ftp_login call returns the constant ACCNT_LOGIN, then an account name is required to complete the login. Account names are used to keep track of machine utilization of groups of people rather than of single users. The ftp_account function must then be used to transmit the correct account name to the server. Most FTP servers do not require and will not prompt for this information.

The FTP library provides several functions to move around in the remote directory tree. The ftp_getcwd function can be used to retrieve the complete path name of the current working directory. The ftp_parent function changes the working directory to the parent of the current directory. The ftp_chdir function can be used to specify the name of a subdirectory or the full path of another directory which should become the new current working directory. An application can even create subdirectories on the remote host by calling ftp_mkdir or delete them with ftp_rmdir.

The ftp_list function is used to obtain either a short or an extended listing of the files and subdirectories in the current working directory. Each directory entry in short or long format is listed on a separate line. For each entry, the callback function provided by the application as an argument to the ftp_list function is called. Once the ftp_list function returns, no more calls to the callback function will be made. Files in the current working directory can be manipulated with the following functions. The ftp_rename function renames an existing file and the ftp_delete function deletes an existing file. Both functions handle only one file per call and do not allow wildcards.

Files can be transferred to or from the remote host one file at a time. First, the transfer type should be set to either a text or a binary type with the ftp_type function. Then single files can be copied to the current directory on the remote host by calling ftp_put or to the local machine by calling ftp_get. Both functions require the procedure address of a callback function as an argument. During an ftp_get operation, the callback function is called one or more times with the data from the remote file. The callback function can at this point write the data to a local disk file or use the data in some other way (e.g. sending it in a DDE exchange or copying it to the clipboard). During an ftp_put operation, the callback function is called one or more times to obtain the data to be stored in the remote file. This data can be read by the callback function from a local disk file or read in some other way (e.g. from the clipboard or received in a DDE exchange).

Once an FTP connection is no longer needed, ftp_close should be called to release the resources allocated for the connection. After performing a logout, this function properly closes down the TCP socket which was used to connect to the remote port. An application must call ftp_close for all connections it has allocated by calling ftp_open.

Function Summary

ftp_abort

Reset FTP connection

ftp_account

Send account name of user

ftp_cancel

Cancel the current command

ftp_capture

Toggle capture of FTP control connection to disk file

ftp_chdir

Change current working directory

ftp_close

Close FTP control connection

ftp_delete

Delete file on server

ftp_direct

Send command over FTP control connection

ftp_error

Get the last error code

ftp_ext_open

Establish FTP control connection with given settings

ftp_get

Transfer file from server to local disk

ftp_getcwd

Get full path of current working directory on server

ftp_handler

Set event callback function

ftp_list

Get listing of current directory in short or long format

ftp_login

Send user name and password of current user

ftp_mkdir

Create subdirectory on server

ftp_open

Establish FTP control connection

ftp_parent

Change current working directory to parent directory

ftp_password

Send password of user

ftp_put

Transfer file from local disk to server

ftp_rename

Rename existing file

ftp_rmdir

Remove subdirectory on server

ftp_type

Set file transfer type

ftp_xopen

Establish FTP control connection to given port


FTP Summary
This widely used library allows you to integrate FTP file transfer capabilities directly into your application with no effort, saving you months of development time. Using the high level calls available in this unique library, you are able to run seamless and automated file transfers directly from your application with minimal or no interaction from your end users.


Function Summaries

Click on a library below to find out what functions it includes:

Windows Sockets

FTP

Telnet

RLIB

SMTP

POP2/POP3

MIME

NNTP

ONC RPC/XDR


Included Libraries

The following libraries are included in the the 32 - bit version of the Distinct TCP/IP SDK:

Windows Sockets

FTP

Telnet

RLIB

SMTP and POP2/POP3

MIME

NNTP

ONC RPC/XDR


MIME Library

The Distinct Multipurpose Internet Mail Protocol (MIME) library provides developers with an API to create MIME or non-MIME messages, or news articles.  A message or news article is created using the create_message function.  This function allows the caller to add any number of attachments to the mail message or news article.  If the create_message function returns successfully, the message will have been created successfully.  The MIME library takes care of many complicated details of the message creation process including encoding and decoding of messages.  This ensures that the calling application only deals with actual user data.

An application uses the extract_message function to separate a message from its attachments.  When invoked, the MIME library will callback with the attachment filename, the level of nesting (if it is a multipart message) and the attachment file type.  If the message is a partial, the library will wait until it gets the remaining parts of the message.  The function extract_message will automatically decode the attachments if they are encoded.

The Distinct MIME library offers additional functions that enable a calling application to encode or decode attachments without having to call create_message or extract_message.  The library contains functions that support base64, quoted-printable, and uuencode/uudecode algorithms.

Function Summary

create_message

Creates a mail or news message

extract_message

Extracts a mail or news message

base64_encode

Encodes a file in base64

base64_decode

Decodes a file encoded in base64

quoted_encode

Encodes a file in quoted-printable

quoted_decode

Decodes a file in quoted-printable

mhlp_uuencode

Uuencodes a file

mhlp_uudecode

Uudecodes a file

mime_options

Sets mime options


MIME Summary
With the MIME library, you can write applications that allow your users to encode and decode e-mail or news messages using Base64, Quoted-Printable, or UUEncode/UUDecode.  Encoding and decoding is performed automatically by the MIME library.  Messages can be RFC 822 (plain) or MIME conformant.  This libary works seamlessly with the SMTP, POP2/POP3, and NNTP libraries.


NNTP Library

The Distinct Network News Transfer Protocol (NNTP) Library provides developers with an API to navigate through all available network news groups on a server and to retrieve or post news articles.

Once a connection has been established with a server using the nntp_(x)open call, a current news group must be selected with the nntp_group command. A complete list of all news groups supported by the server can be obtained with the nntp_list function. Within the current news group, articles or portions of articles can be retrieved with the nntp_article call. An application can post its own news articles with calls to nntp_post.

When a connection is no longer needed, it must be closed with a call to nntp_quit. Connections should not be kept open when not in use since they consume valuable system resources. An application must close all open connections before it terminates.

Most functions in the NNTP Library wait for a reply from the NNTP server before returning to the caller. Because communication links or servers sometimes go down, these functions use a default timeout of 20 seconds before returning the error value NNTP_TIMED_OUT if no response was received. This timeout value can be changed by editing or creating the following entry in the SOCKET.INI file (usually located in the Windows directory).

[NNTP]

Timeout=20

While waiting for a reply to a command or while waiting for a data transfer to complete, most functions in the NNTP Library yield control to Windows. This allows applications to process messages while an NNTP operation is in progress. Without yielding, the system would appear to be frozen for the entire duration of each NNTP operation. By default, yielding is therefore enabled but can be disabled if necessary with the nntp_option call. Yielding control to Windows is done by the NNTP Library by frequently calling the nntp_yield function during lengthy operations. This function is exported in case the calling application also needs to yield, for example while processing data in a callback function. The calling application can also define its own yielding function to be called instead of the default yielding function (nntp_yield may then be called from within the applications yielding function).

Function Summary

nntp_article

Retrieve all or a portion of an article or get article statistics

nntp_date

Get current time and date formatted as specified in RFC 850

nntp_forward

Forward news article to next server

nntp_group

Select current news group

nntp_help

Retrieve remote help instructions

nntp_list

Retrieve list of available news groups

nntp_new

Retrieve list of new groups or new articles

nntp_open

Open connection with NNTP server

nntp_option

Set connection option

nntp_position

Set current article

nntp_post

Post news article

nntp_quit

Disconnect from NNTP server

nntp_reply

Get last reply of NNTP server

nntp_slave

Inform server of slave status

nntp_xopen

Asynchronous version of nntp_open

nntp_xquit

Cancel asynchronous connect or operation in progress

nntp_yield

Yield control to Windows


NNTP Summary
The Network News Transfer Protocol (NNTP) library allows you to write custom news readers or to integrate news reader functionality into any application. You can read, list or post news articles using this high level API.


ONC RPC/XDR Library
The ONC RPC/XDR Library

The Distinct RPC/XDR Toolkit contains all necessary tools for developing both Windows client and Windows server portions of a distributed network application using remote procedure calls (RPCs). Such an application can be run on a heterogeneous network and will be able to communicate with clients and servers of any architecture because data is transferred using the external data representation (XDR) in a format independent of the processors and operating systems involved. The Distinct RPC/XDR Library is a Microsoft Windows dynamic link library (DLL) which can be used by any Windows application. It is an extension of the Microsoft Windows Software Development Kit (SDK) and allows a Windows application to issue remote procedure calls to a network server and to register its own remote procedure services for use by one or more network clients.

The client portion of the Distinct RPC/XDR Library contains both a high level and a low level interface to RPC calls. The high level interface consists of rpc_call and callrpc (the two functions only differ in how the server address is specified). Both functions default to the UDP/IP transport protocol. To use the low level interface, the application must first call clntudp_create or clnttcp_create to set up an RPC client connection using either the UDP/IP or the TCP/IP transport protocol. Then one or more RPC calls can be issued by calling clnt_call. Finally, the application must free all resources allocated to the RPC client connection by calling clnt_destroy. Both interface levels include the same functionality. The caller must provide far pointers to the argument ('out') and result ('in') buffers (usually containing basic data types or structures, sometimes arrays or even linked lists) along with pointers to the routines used to convert data to and from a host independent network format: the external data representation (XDR). The outgoing data is then encoded into network format using the XDR routine specified and the RPC call is sent to the server. When the RPC reply is received, the incoming data is decoded into host (local) format using the given XDR routine. All necessary byte swapping is performed automatically by the XDR routines. RPC calls do not return to the caller until an answer has been received or until a timeout has occurred.

The Distinct RPC/XDR Library includes a port mapper daemon which is dynamically loaded as soon as the first RPC server registers a TCP/IP or UDP/IP service and unloaded after the last RPC server terminates its service(s). The RPC Information utility (RPCINFO.EXE) can be used to obtain a listing of all registered services and their ports either on the local machine or on other hosts on the network. Server applications can check if the service is already registered using pmap_set and can unregister the service using pmap_unset. The pmap_getport function can be used to look up the port number of an RPC service registered on any host (including the local machine). With the pmap_getmaps function, an application can obtain a list of all the RPC services registered on the local or any remote machine.

The server portion of the Distinct RPC/XDR Library allows Windows application or DLL to register one or more services for the UDP/IP or TCP/IP transport protocol. Each such service has associated with it an XDR encode routine, an XDR decode routine and a service routine to be called by the port mapper daemon whenever a request for the service arrives. A server process associates its service number (e.g. 100002 for the rusers service) with an actual port on the local machine by first allocating the necessary resources with a call to svctcp_create or svcudp_create depending on the desired transport protocol. Many servers provide the same service for both UDP/IP and TCP/IP. In this case, the same service routine and the same XDR routines can be used for both transport protocols. Next, the port mapper is instructed to add the new service to the list of available services on the local machine by calling svc_register. Every time an RPC request for a particular service arrives on the local port, the port mapper calls the associated service routine. Upon completion of the request, the service routine must call svc_sendreply to transmit the reply buffer to the client (in case of an error, the svcerr_ functions may be used to return an error message). Before the server terminates, it must call svc_destroy for all of the services it registered to free all resources allocated to the services.

External data representation (XDR) is used to encode data into a host independent network data format and decode network data back into the host specific data format. Data sent as an argument to an RPC call and the data making up the reply part of the call are transferred in network data format. Before this data can be used, the correct XDR routine must be called for decoding. Any byte swapping or differences in the length of data elements (for example, two versus four byte integers) are handled transparently in the XDR routines. The XDR primitives included in this library can be used to encode or decode call arguments and results directly or to build more complex custom XDR routines.

The Distinct RPC/XDR Library also allows encoding and decoding of data to and from XDR memory buffers ('streams') without actually making a remote procedure call. Applications can, for example, encode and decode data that is transmitted over sockets with a protocol other than RPC. The XDR stream functions include  xdr_create, xdr_destroy, xdr_put_long, xdr_get_long, xdr_put_bytes, xdr_get_bytes, xdr_set_pos and xdr_get_pos.

RPC/XDR Toolkit Files

The Distinct RPC/XDR Toolkit includes the following files:

D32-RPC.DLL

This file contains the actual dynamic link library and should be copied into your Windows directory, into the same directory as your application, or into a directory included in your path. Microsoft Windows must be able to locate this file whenever a Distinct RPC/XDR Library application is started.

D32-RPC.H

This C and C++ header file includes definitions of all constants and structures used in Distinct RPC/XDR Library functions in addition to function prototypes. It should be included in all source modules to allow for argument type checking.

D32-RPC.LIB

This library link file must be added to your project or must be specified on the linker command line to resolve references to Distinct RPC/XDR Library functions.

D32-RPC.HLP

This Windows Help file contains a copy of the printed Distinct RPC/XDR Library reference as on-line help.

D32-RPC.PAS

This Turbo Pascal or Delphi for Windows module includes definitions of all constants and structures used in Distinct RPC/XDR Library functions in addition to function declarations. The module name rpc must be included in the uses statement in your Turbo Pascal or Delphi for Windows source module.

PMAP32.EXE

This file contains the port mapper daemon and should be copied into your Windows directory, into the same directory as your application, or into a directory included in your path. The port mapper is dynamically loaded as soon as the first RPC server registers a TCP/IP or UDP/IP service and unloaded after the last server terminates its service(s). Microsoft Windows must be able to locate this file whenever a Distinct RPC/XDR Library server application is started.

RPCGEN.EXE

This RPC Protocol Compiler generates the C source code and the C header files for XDR routines for your custom data types from an XDR definition file you supply.

RPCINF32.EXE

This application obtains a list of all registered RPC services from the local machine or from any host on the network.

In addition, sample programs with source code in C and Pascal are copied to your hard disk during installation of the Distinct RPC/XDR Toolkit. The Pascal sample contains an RPC client which uses rpc_call to query a server for a list of all users currently logged in. Both client and server C source code are included for this program. The C client program also demonstrates both the low level and the high level RPC call interface.

Function Summary

Blocking RPC Client Functions

The following set of functions allows an RPC client to issue remote procedure calls. These calls will block, i.e. the function calls will not return until an answer has been received or until the calls time out. Some functions always use the UDP protocol, others require the caller to specify the protocol to be used.

callrpc ()

Issue remote procedure call to specified server using UDP protocol.

clnt_broadcast ()

Broadcast a procedure request to all servers on the network.

clnt_call ()

Issue remote procedure call on established UDP or TCP connection.

clnt_create ()

Create RPC client structure using either the TCP or the UDP protocol.

clnt_destroy ()

Free all resources allocated for established connection.

clnttcp_create ()

Create connection with specified server using TCP protocol.

clntudp_create ()

Create connection with specified server using UDP protocol.

rpc_broadcast ()

Broadcast remote procedure call to all servers on local network.

rpc_call ()

Issue remote procedure call to specified server using TCP or UDP protocol.

Asynchronous RPC Client Functions

This set of functions allows an RPC client to issue asynchronous remote procedure calls.

rac_drop ()

Terminate asynchronous remote procedure call in progress.

rac_poll ()

Poll status of asynchronous remote procedure call in progress.

rac_recv ()

Obtain results of asynchronous remote procedure call.

rac_send ()

Issue asynchronous remote procedure call.

Port Mapper Functions

Every RPC server contains a port mapper daemon (a background process usually invisible to the user), which maintains a mapping between the service numbers of the RPC services currently active on the server and the protocol and port on which they are available. Before making an RPC call, a client first has to find out, with an RPC call to the port mapper, on which port the desired service is running.

pmap_getmaps ()

Query specified server for list of available services.

pmap_getport ()

Retrieve UDP or TCP port number of specified service.

pmap_rmtcall ()

Request remote port mapper to execute specified command.

pmap_set ()

Register given service with local port mapper.

pmap_unset ()

Remove specified service from local machine.

RPC Server Functions

The following set of functions allows an RPC server to register and unregister the procedures it provides to clients. These procedures are maintained by the port mapper on the local machine. Procedures must be registered separately for the UDP and the TCP protocol. Functions are also available for retrieving arguments supplied by the client, sending back a reply and returning various errors to the client.

registerrpc ()

Register service using UDP protocol with local port mapper.

svc_destroy ()

Free all resources allocated for given service.

svc_freeargs ()

Free argument buffer of remote service request.

svc_getargs ()

Get arguments for service supplied by remote client.

svc_getcaller ()

Get internet address of current client.

svc_register ()

Register service using UDP or TCP protocol with local port mapper.

svc_run ()

Start accepting service requests from clients.

svc_sendreply ()

Transmit reply data structure to remote client.

svc_unregister ()

Remove entry for given service from local port mapper table.

svcerr_auth ()

Return "Authentication error" to client.

svcerr_decode ()

Return "Unable to decode arguments" error to client.

svcerr_noproc ()

Return "Procedure not available" error to client.

svcerr_noprog ()

Return "Program not available" error to client.

svcerr_progvers ()

Return "Program version not available" error to client.

svcerr_systemerr ()

Return "System error" to client.

svcerr_weakauth ()

Return "Refuse to perform procedure" error to client.

svctcp_create ()

Allocate resources for RPC service using TCP transport protocol.

svcudp_create ()

Allocate resources for RPC service using UDP transport protocol.

Authentication Routines

auth_destroy ()

Destroy authentication information.

authnone_create ()

Create empty authentication information.

authsys_create ()

Create system authentication information.

authunix_create ()

Create UNIX style authentication information.

Generic RPC Routines

clnt_control ()

Change or retrieve information about client handle.

clnt_geterr ()

Get error structure from client handle.

clnt_geterror ()

Get last error in failed client operation.

clnt_perror ()

Display message box with error from last performed client operation.

clnt_sperror ()

Return string corresponding to last error in failed client operation.

smtp_data

Send message data


ONC RPC/XDR Summary
Built on top of Windows Sockets, Distinct RPC implements SUN Microsystems’ Remote Procedure Call (ONC RPC) specification. Distinct RPC provides an advanced client/server programming environment that is easy to use. It delivers a mechanism whereby one process (the “client” process) can have another process (the “server” process) execute a procedure call, as if it was a subroutine on the local system. Because the client and the server are two separate processes, they no longer have to reside on the same physical machine. Distinct RPC implements client and server RPC as a DLL, and includes support for the eXternal Data Representation (XDR) standard used for portable data transmission. An RPCGEN utility is included. Distinct RPC opens a new window for programmers to write distributed programs with minimal effort.


POP2 / POP3 Library

The Distinct Post Office Protocol (POP) Library provides developers with a consistent API to both version 2 and version 3 of POP. POP is a service which usually runs on mail servers (such as UNIX workstations) to allow mail clients (usually PCs) to retrieve mail stored for them in their private mail box.

Once a connection has been established with a server using the pop_(x)open call, information about the available messages in this mail box can be obtained with the pop_stat and pop_list functions. The pop_stat function determines the number of messages and their total size in bytes and the pop_list function retrieves the size in bytes of each available message. Messages can be read with the pop_retr function and, once they are downloaded to the PC, removed from the server mail box with the pop_dele function.

When a connection is no longer needed, it must be closed with a call to pop_quit. Connections should not be kept open when not in use since they consume valuable system resources. An application must close all open connections before it terminates.

Most functions in the POP Library wait for a reply from the POP server before returning to the caller. Because communication links or servers sometimes go down, these functions use a default timeout of 20 seconds before returning the error value POP_TIMED_OUT if no response was received. This timeout value can be changed by editing or creating the following entry in the SOCKET.INI file (usually located in the Windows directory).

[POP]

Timeout=20

While waiting for a reply to a command or while waiting for a data transfer to complete, most functions in the POP Library yield control to Windows. This allows applications to process messages while a POP operation is in progress. Without yielding, the system would appear to be frozen for the entire duration of each POP operation. By default, yielding is therefore enabled but can be disabled if necessary with the pop_opts call. Yielding control to Windows is done by the POP Library by frequently calling an internal yielding function during lengthy operations. The calling application can also define its own yielding function to be called instead of the default yielding function.

Function Summary

pop_dele

Delete specified message

pop_list

Get listing of available messages

pop_noop

Do nothing

pop_open

Open connection with POP server

pop_opts

Set connection option

pop_quit

Close connection with POP server

pop_retr

Retrieve specified message

pop_rply

Get last server reply

pop_rset

Reset POP server

pop_stat

Get statistics about available messages

pop_xopen

Asynchronous version of pop_open

pop_xquit

Cancel asynchronous connect or operation in progress


RLIB Library
The RLIB Library

The Distinct Remote Utilities Library provides developers with an API to integrate remote shell (rsh), remote login (rlogin), remote execution (rexec) and remote copy (rcp) capabilities into their applications. This library takes care of establishing the connection and any login procedures that may be required for the execution of the command.

These functions require the remote machine to be configured for remote command or remote copy execution. Each remote host must have a file /etc/hosts.equiv containing an equivalence list of remote hosts and user names. Each user may also have a private equivalence list in a file .rhosts in their login directory. If the necessary permissions are not set on the remote host, then the command will not be executed.

The rcp function copies files between two machines. This function does not prompt for passwords. Instead, the specified user name must exist on the remote machine and must be set up to allow command execution via rsh. Options to transfer directories recursively and to preserve the date and time of the source files are available. The rcp function is meant to copy files between hosts. An attempt to copy a file to itself will result in a corrupted file.

The rexec function connects to the specified remote host to execute a given command. User name and password are specified to login to the remote host. If the connection succeeds, then the command is executed and the resulting output is returned to the application. The rexec function normally terminates when the remote command has finished executing.

The rlogin function connects your application on the local system to the remote host. While logging in, the remote machine will prompt for a user name and password just like during a standard Telnet login. The remote terminal type is the same as your local terminal type. All echoing takes place on the remote system so that (except for network delays) the rlogin procedure is transparent. The rlogin function does not terminate after the execution of the function. Instead, it allows the application to keep executing commands. This can be used to execute interactive commands such as vi.

The rsh function connects to the shell utility of the remote host to execute the specified command. No provision is made for specifying the password. The rsh function normally terminates when the remote command is executed completely. Shell meta characters can be used as part of the command (for example, cat test >> test1 appends test to test1).

Function Summary

rcp

Remote file copy

rexec

Remote execution

rlogin

Remote login

rsh

Remote shell


RLIB Summary
This library allows the execution of remote commands directly from within your application. Using the API calls for REXEC (Remote Execution), RLOGIN (Remote Login), RSH (Remote Shell) or RCP (Remote Copy), this library takes care of the entire connection process and the issuing of the commands. REXEC, RSH and RLOGIN return the open socket descriptor to the programmer when this is done. RCP allows copying between two remote machines and can preserve the directory structure as well as file date and time.


SMTP Library

The Distinct Simple Mail Transfer Protocol (SMTP) Library provides developers with an API to a mail delivery service which usually runs on mail servers (such as UNIX workstations) to allow mail clients (usually PCs) to send mail to other mail servers or clients on the network.

Once a connection has been established with a server using the smtp_(x)helo call, a new message transfer is initiated by calling smtp_mail, smtp_send, smtp_saml or smtp_soml. The only difference between these four calls lies in how messages are delivered to their recipients. The second step to sending a message is to specify one or more recipients by calling the smtp_rcpt function one or more times. The third and final step to deliver a message is to call the smtp_data function to actually transfer the required message headers and the body of the message. These three steps can be repeated as often as needed to send all queued messages.

When a connection is no longer needed, it must be closed with a call to smtp_quit. Connections should not be kept open when not in use since they consume valuable system resources. An application must close all open connections before it terminates.

Most functions in the SMTP Library wait for a reply from the SMTP server before returning to the caller. Because communication links or servers sometimes go down, these functions use a default timeout of 20 seconds before returning the error value SMTP_TIMED_OUT if no response was received. This timeout value can be changed by editing or creating the following entry in the SOCKET.INI file (usually located in the Windows directory).

[SMTP]

Timeout=20

While waiting for a reply to a command or while waiting for a data transfer to complete, most functions in the SMTP Library yield control to Windows. This allows applications to process messages while an SMTP operation is in progress. Without yielding, the system would appear to be frozen for the entire duration of each SMTP operation. By default, yielding is therefore enabled but can be disabled if necessary with the smtp_opts call. Yielding control to Windows is done by the SMTP Library by frequently calling an internal yielding function during lengthy operations. The calling application can also define its own yielding function to be called instead of the default yielding function.

Function Summary

smtp_date

Get current time and date in RFC 822 format

smtp_expn

Send expand command

smtp_helo

Open connection with SMTP server

smtp_help

Send help command

smtp_mail

Send mail command

smtp_noop

Do nothing

smtp_opts

Set connection option

smtp_quit

Close connection with SMTP server

smtp_rcpt

Send recipient command

smtp_rply

Get last server reply

smtp_rset

Send reset command

smtp_saml

Send send and mail command

smtp_send

Send send command

smtp_soml

Send send or mail command

smtp_turn

Send turn command

smtp_vrfy

Send verify command

smtp_xhelo

Asynchronous version of smtp_helo

smtp_xquit

Cancel asynchronous connect or operation in progress


SMTP and POP2/POP3
These libraries can be used on their own or in conjunction with each other to produce fully functional e-mail packages. The Simple Mail Transfer Protocol (SMTP) is used for sending out e-mail whereas the Post Office Protocol (POP2 and POP3) is typically used to receive e-mail directly on the PC.


Telnet Library
The Telnet Library

The Distinct Telnet library provides developers with an API to manage one or more Telnet connections. A new connection is established by calling tnet_open. This function allows the caller to connect to any TCP port on the given host (not just to the default Telnet port). The caller can also specify the terminal type that will be supported. Once the tnet_open call returns successfully, a TCP connection with the remote host has been established. The Telnet library takes care of all necessary option negotiations according to the Telnet protocol definition and filters out and replies to Telnet escape sequences in the incoming data stream. This ensures that the calling application only deals with actual user data.

The Telnet library uses an upcall mechanism to notify the application that data has arrived on one of its connections. In the tnet_open call, the caller specifies a window handle and the message the window should receive when data is available. By choosing different messages and/or using different window handles, an application can easily and efficiently maintain several Telnet connections. Although this is not recommended, an application can also poll a Telnet connection regularly for the availability of data by calling tnet_status. In general, a polling mechanism slows down Windows because not enough time is spent yielding control to other applications. This behavior can seriously impact Windows performance. Note however that calling tnet_status once after receiving an upcall before calling tnet_read does not add significant overhead. Such a call could be used to allow the application to allocate a buffer large enough to hold all the available data.

Whenever an application calls tnet_read, any Telnet option negotiation requests and other escape sequences are filtered out by the Telnet library. If the filtered sequence requires that an answer be sent to the remote host, then the answer is put into the TCP send queue of the associated socket at this point. Because upcalls are generated whenever any data arrives regardless of the type of data (user data or Telnet sequence), tnet_read may return with less bytes read than the return value of tnet_status indicated. Immediately after a connection has been established, tnet_read may even return zero bytes one or more times. This is normal behavior and simply indicates that Telnet negotiations are being processed.

Because network traffic is interrupt driven (that is, unlike in a message passing system, the current process is interrupted to service the incoming packet interrupt request), it is possible for new data to arrive for a Telnet connection while the tnet_read function is in progress. This means that another upcall will be in the applications message queue when the tnet_read call returns. If the tnet_read function was called with a length larger than the number of bytes returned by the tnet_status function, then some or all of the data associated with this new upcall may already have been read. If all the data has been read, then the second call (in response to the second upcall) will return zero.

Once a Telnet connection is no longer needed, tnet_close can be called to release the resources allocated for the connection. This function properly closes down the TCP socket which was used to connect to the remote port. It does not perform a logout. An application must call tnet_close for all connections it has allocated by calling tnet_open. The tnet_close function must be called even if the application has received an upcall indicating that the remote host has closed down the connection.

Function Summary

tnet_abort

Abort the Telnet connection

tnet_binary

Enable or disable binary mode

tnet_close

Close the Telnet connection

tnet_error

Get the last error

tnet_getc

Read one byte from the Telnet connection

tnet_local

Disable remote echo mode

tnet_oob_read

Read urgent data from the Telnet connection

tnet_oob_status

Check for urgent data

tnet_oob_write

Write urgent data to the Telnet connection

tnet_open

Establish a Telnet connection

tnet_option_status

Get the current state of a Telnet option

tnet_putc

Write one byte to the Telnet connection

tnet_read

Read data from the Telnet connection

tnet_remote

Set remote echo mode

tnet_status

Get number of bytes available to read

tnet_write

Write data to the Telnet connection

tnet_x_open

Establish a Telnet connection


Telnet Summary
The Telnet Library allows you to port existing terminal emulators to a TCP/IP environment with minimum effort. New emulators can also be written without making direct socket calls. This library also allows you to build Telnet functions directly into any custom applications.


Windows Sockets Library
The Windows Sockets Library

The Windows Sockets specification defines a network programming interface for Microsoft Windows which is based on the "socket" paradigm popularized in the Berkeley Software Distribution (BSD) from the University of California at Berkeley. It encompasses both familiar Berkeley socket style routines and a set of Windows-specific extensions designed to allow the programmer to take advantage of the message-driven nature of Windows.

The Windows Sockets specification is intended to provide a single API to which application developers can program and multiple network software vendors can conform. Furthermore, in the context of a particular version of Microsoft Windows, it defines a binary interface (ABI) such that an application written to the Windows Sockets API can work with a conformant protocol implementation from any network software vendor. This specification thus defines the library calls and associated semantics to which an application developer can program and which a network software vendor can implement.

Applications which are capable of operating with any "Windows Sockets Compliant" protocol implementation will be considered as having a "Windows Sockets Interface" and will be referred to as "Windows Sockets Applications".

Socket functions

accept()

Accept a connection on a socket

bind()

Associate a local address with a socket.

closesocket()

Close a socket

connect()

Initiate a connection on the specified socket.

getpeername()

Retrieve the name of the peer connected to the specified socket

getsockname()

Retrieve the current name for the specified socket

getsockopt()

Retrieve options associated with the specified socket.

htonl()

Convert a 32-bit quantity from host byte order to network byte order.

htons()

Convert a 16-bit quantity from host byte order to network byte order.

inet_addr()

Converts a character string representing a dotted decimal address to a network address value.

inet_ntoa()

Converts a network address value to a string in dotted decimal format.

ioctlsocket()

Provide control for sockets.

listen()

Listen for incoming connections on a specified socket.

ntohl()

Convert a 32-bit quantity from network byte order to host byte order.

ntohs()

Convert a 16-bit quantity from network byte order to host byte order.

recv()

Receive data from a connected socket.

recvfrom()

Receive data from either a connected or unconnected socket.

select()

Perform synchronous I/O multiplexing.

send()

Send data to a connected socket.

sendto()

Send data to either a connected or unconnected socket.

setsockopt()

Store options associated with the specified socket

shutdown()

Shut down part of a full-duplex connection.

socket()

Create an endpoint for communication and return a socket.

Database Functions

gethostbyaddr()

Get host information corresponding to a network address.

gethostbyname()

Get host information corresponding to a host name.

gethostname

Retrieve the name of the local host.

getprotobyname()

Get protocol information corresponding to a protocol name.

getprotobynumber()

Get protocol information corresponding to a protocol number.

getservbyname()

Get service information corresponding to a service name.

getservbyport()

Get service information corresponding to a port and protocol.

Microsoft Windows-specific Extension Functions

WSAAsyncGetHostByAddr()

Get host information corresponding to a network address. - asynchronous version.

WSAAsyncGetHostByName()

Get host information corresponding to a host name - asynchronous version.

WSAAsyncGetProtoByName()

Get protocol information corresponding to a protocol name - asynchronous version.

WSAAsyncGetProtoByNumber()

Get protocol information corresponding to a protocol number - asynchronous version.

WSAAsyncGetServByName()

Get service information corresponding to a service name - asynchronous version.

WSAAsyncGetServByPort()

Get service information corresponding to a port and protocol - asynchronous version.

WSAAsyncSelect()

Perform asynchronous version of select().

WSACancelAsyncRequest()

Cancel an incomplete asynchronous operation.

WSACancelBlockingCall()

Cancel an outstanding "blocking" API call.

WSACleanup()

Terminate use of Windows Sockets DLL.

WSAGetLastError()

Get the error status for the last operation which failed

WSAIsBlocking()

Determine if a blocking call is in progress.

WSASetBlockingHook()

Establish an application-specific blocking hook function.

WSASetLastError()

Set the error code which can be retrieved by WSAGetLastError().

WSAStartup()

Initiate the use of the Windows Sockets DLL.

WSAUnhookBlockingHook()

Restore the default blocking hook function.


Windows Sockets Summary
This API lets you develop a single TCP/IP application to run on Windows 95 and Windows NT. A program written to this API will run over the Distinct TCP/IP as well as over the TCP/IP protocol stacks provided by vendors who are fully compliant with the specification when they will be available.